<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>The png Module &mdash; PyPNG v0.0.11 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.0.11',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="PyPNG v0.0.11 documentation" href="index.html" />
    <link rel="next" title="PNG: Chunk by Chunk" href="chunk.html" />
    <link rel="prev" title="PyPNG Code Examples" href="ex.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="chunk.html" title="PNG: Chunk by Chunk"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="ex.html" title="PyPNG Code Examples"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">PyPNG v0.0.11 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-png">
<h1>The png Module<a class="headerlink" href="#module-png" title="Permalink to this headline">¶</a></h1>
<p>Pure Python PNG Reader/Writer</p>
<p>This Python module implements support for PNG images (see PNG
specification at <a class="reference external" href="http://www.w3.org/TR/2003/REC-PNG-20031110/">http://www.w3.org/TR/2003/REC-PNG-20031110/</a> ). It reads
and writes PNG files with all allowable bit depths (1/2/4/8/16/24/32/48/64
bits per pixel) and colour combinations: greyscale (1/2/4/8/16 bit); RGB,
RGBA, LA (greyscale with alpha) with 8/16 bits per channel; colour mapped
images (1/2/4/8 bit).  Adam7 interlacing is supported for reading and
writing.  A number of optional chunks can be specified (when writing)
and understood (when reading): <tt class="docutils literal"><span class="pre">tRNS</span></tt>, <tt class="docutils literal"><span class="pre">bKGD</span></tt>, <tt class="docutils literal"><span class="pre">gAMA</span></tt>.</p>
<p>For help, type <tt class="docutils literal"><span class="pre">import</span> <span class="pre">png;</span> <span class="pre">help(png)</span></tt> in your python interpreter.</p>
<p>A good place to start is the <a title="png.Reader" class="reference internal" href="#png.Reader"><tt class="xref docutils literal"><span class="pre">Reader</span></tt></a> and <a title="png.Writer" class="reference internal" href="#png.Writer"><tt class="xref docutils literal"><span class="pre">Writer</span></tt></a> classes.</p>
<p>Requires Python 2.3.  Limited support is available for Python 2.2, but
not everything works.  Best with Python 2.4 and higher.  Installation is
trivial, but see the <tt class="docutils literal"><span class="pre">README.txt</span></tt> file (with the source distribution)
for details.</p>
<p>This file can also be used as a command-line utility to convert
<a class="reference external" href="http://netpbm.sourceforge.net/">Netpbm</a> PNM files to PNG, and the reverse conversion from PNG to
PNM. The interface is similar to that of the <tt class="docutils literal"><span class="pre">pnmtopng</span></tt> program from
Netpbm.  Type <tt class="docutils literal"><span class="pre">python</span> <span class="pre">png.py</span> <span class="pre">--help</span></tt> at the shell prompt
for usage and a list of options.</p>
<div class="section" id="a-note-on-spelling-and-terminology">
<h2>A note on spelling and terminology<a class="headerlink" href="#a-note-on-spelling-and-terminology" title="Permalink to this headline">¶</a></h2>
<p>Generally British English spelling is used in the documentation.  So
that&#8217;s &#8220;greyscale&#8221; and &#8220;colour&#8221;.  This not only matches the author&#8217;s
native language, it&#8217;s also used by the PNG specification.</p>
<p>The major colour models supported by PNG (and hence by PyPNG) are:
greyscale, RGB, greyscale&#8211;alpha, RGB&#8211;alpha.  These are sometimes
referred to using the abbreviations: L, RGB, LA, RGBA.  In this case
each letter abbreviates a single channel: <em>L</em> is for Luminance or Luma or
Lightness which is the channel used in greyscale images; <em>R</em>, <em>G</em>, <em>B</em> stand
for Red, Green, Blue, the components of a colour image; <em>A</em> stands for
Alpha, the opacity channel (used for transparency effects, but higher
values are more opaque, so it makes sense to call it opacity).</p>
</div>
<div class="section" id="a-note-on-formats">
<h2>A note on formats<a class="headerlink" href="#a-note-on-formats" title="Permalink to this headline">¶</a></h2>
<p>When getting pixel data out of this module (reading) and presenting
data to this module (writing) there are a number of ways the data could
be represented as a Python value.  Generally this module uses one of
three formats called &#8220;flat row flat pixel&#8221;, &#8220;boxed row flat pixel&#8221;, and
&#8220;boxed row boxed pixel&#8221;.  Basically the concern is whether each pixel
and each row comes in its own little tuple (box), or not.</p>
<p>Consider an image that is 3 pixels wide by 2 pixels high, and each pixel
has RGB components:</p>
<p>Boxed row flat pixel:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">list</span><span class="p">([</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">],</span>
     <span class="p">[</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">])</span>
</pre></div>
</div>
<p>Each row appears as its own list, but the pixels are flattened so that
three values for one pixel simply follow the three values for the previous
pixel.  This is the most common format used, because it provides a good
compromise between space and convenience.  PyPNG regards itself as
at liberty to replace any sequence type with any sufficiently compatible
other sequence type; in practice each row is an array (from the array
module), and the outer list is sometimes an iterator rather than an
explicit list (so that streaming is possible).</p>
<p>Flat row flat pixel:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span>
 <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">,</span> <span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">]</span>
</pre></div>
</div>
<p>The entire image is one single giant sequence of colour values.
Generally an array will be used (to save space), not a list.</p>
<p>Boxed row boxed pixel:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nb">list</span><span class="p">([</span> <span class="p">(</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">),</span> <span class="p">(</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">),</span> <span class="p">(</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">)</span> <span class="p">],</span>
     <span class="p">[</span> <span class="p">(</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">),</span> <span class="p">(</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">),</span> <span class="p">(</span><span class="n">R</span><span class="p">,</span><span class="n">G</span><span class="p">,</span><span class="n">B</span><span class="p">)</span> <span class="p">])</span>
</pre></div>
</div>
<p>Each row appears in its own list, but each pixel also appears in its own
tuple.  A serious memory burn in Python.</p>
<p>In all cases the top row comes first, and for each row the pixels are
ordered from left-to-right.  Within a pixel the values appear in the
order, R-G-B-A (or L-A for greyscale&#8211;alpha).</p>
<p>There is a fourth format, mentioned because it is used internally,
is close to what lies inside a PNG file itself, and has some support
from the public API.  This format is called packed.  When packed,
each row is a sequence of bytes (integers from 0 to 255), just as
it is before PNG scanline filtering is applied.  When the bit depth
is 8 this is essentially the same as boxed row flat pixel; when the
bit depth is less than 8, several pixels are packed into each byte;
when the bit depth is 16 (the only value more than 8 that is supported
by the PNG image format) each pixel value is decomposed into 2 bytes
(and <cite>packed</cite> is a misnomer).  This format is used by the
<a title="png.Writer.write_packed" class="reference internal" href="#png.Writer.write_packed"><tt class="xref docutils literal"><span class="pre">Writer.write_packed()</span></tt></a> method.  It isn&#8217;t usually a convenient
format, but may be just right if the source data for the PNG image
comes from something that uses a similar format (for example, 1-bit
BMPs, or another PNG file).</p>
</div>
<div class="section" id="and-now-my-famous-members">
<h2>And now, my famous members<a class="headerlink" href="#and-now-my-famous-members" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="png.Reader">
<em class="property">
class </em><tt class="descclassname">png.</tt><tt class="descname">Reader</tt><big>(</big><em>_guess=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#png.Reader" title="Permalink to this definition">¶</a></dt>
<dd><p>PNG decoder in pure Python.</p>
<p>Create a PNG decoder object.</p>
<p>The constructor expects exactly one keyword argument. If you
supply a positional argument instead, it will guess the input
type. You can choose among the following keyword arguments:</p>
<dl class="docutils">
<dt>filename</dt>
<dd>Name of input file (a PNG file).</dd>
<dt>file</dt>
<dd>A file-like object (object with a read() method).</dd>
<dt>bytes</dt>
<dd><tt class="docutils literal"><span class="pre">array</span></tt> or <tt class="docutils literal"><span class="pre">string</span></tt> with PNG data.</dd>
</dl>
<dl class="method">
<dt id="png.Reader.asDirect">
<tt class="descname">asDirect</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.asDirect" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the image data as a direct representation of an
<tt class="docutils literal"><span class="pre">x</span> <span class="pre">*</span> <span class="pre">y</span> <span class="pre">*</span> <span class="pre">planes</span></tt> array.  This method is intended to remove the
need for callers to deal with palettes and transparency
themselves.  Images with a palette (colour type 3)
are converted to RGB or RGBA; images with transparency (a
<tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk) are converted to LA or RGBA as appropriate.
When returned in this format the pixel values represent the
colour value directly without needing to refer to palettes or
transparency information.</p>
<p>Like the <a title="png.Reader.read" class="reference internal" href="#png.Reader.read"><tt class="xref docutils literal"><span class="pre">read()</span></tt></a> method this method returns a 4-tuple:</p>
<p>(<em>width</em>, <em>height</em>, <em>pixels</em>, <em>meta</em>)</p>
<p>This method normally returns pixel values with the bit depth
they have in the source image, but when the source PNG has an
<tt class="docutils literal"><span class="pre">sBIT</span></tt> chunk it is inspected and can reduce the bit depth of
the result pixels; pixel values will be reduced according to
the bit depth specified in the <tt class="docutils literal"><span class="pre">sBIT</span></tt> chunk (PNG nerds should
note a single result bit depth is used for all channels; the
maximum of the ones specified in the <tt class="docutils literal"><span class="pre">sBIT</span></tt> chunk.  An RGB565
image will be rescaled to 6-bit RGB666).</p>
<p>The <em>meta</em> dictionary that is returned reflects the <cite>direct</cite>
format and not the original source image.  For example, an RGB
source image with a <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk to represent a transparent
colour, will have <tt class="docutils literal"><span class="pre">planes=3</span></tt> and <tt class="docutils literal"><span class="pre">alpha=False</span></tt> for the
source image, but the <em>meta</em> dictionary returned by this method
will have <tt class="docutils literal"><span class="pre">planes=4</span></tt> and <tt class="docutils literal"><span class="pre">alpha=True</span></tt> because an alpha
channel is synthesized and added.</p>
<p><em>pixels</em> is the pixel data in boxed row flat pixel format (just
like the <a title="png.Reader.read" class="reference internal" href="#png.Reader.read"><tt class="xref docutils literal"><span class="pre">read()</span></tt></a> method).</p>
<p>All the other aspects of the image data are not changed.</p>
</dd></dl>

<dl class="method">
<dt id="png.Reader.asFloat">
<tt class="descname">asFloat</tt><big>(</big><em>maxval=1.0</em><big>)</big><a class="headerlink" href="#png.Reader.asFloat" title="Permalink to this definition">¶</a></dt>
<dd>Return image pixels as per <a title="png.Reader.asDirect" class="reference internal" href="#png.Reader.asDirect"><tt class="xref docutils literal"><span class="pre">asDirect()</span></tt></a> method, but scale
all pixel values to be floating point values between 0.0 and
<em>maxval</em>.</dd></dl>

<dl class="method">
<dt id="png.Reader.asRGB">
<tt class="descname">asRGB</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.asRGB" title="Permalink to this definition">¶</a></dt>
<dd>Return image as RGB pixels.  Greyscales are expanded into RGB
triplets.  An alpha channel in the source image will raise an
exception.  The return values are as for the <a title="png.Reader.read" class="reference internal" href="#png.Reader.read"><tt class="xref docutils literal"><span class="pre">read()</span></tt></a> method
except that the <em>metadata</em> reflect the returned pixels, not the
source image.  In particular, for this method
<tt class="docutils literal"><span class="pre">metadata['greyscale']</span></tt> will be <tt class="xref docutils literal"><span class="pre">False</span></tt>.</dd></dl>

<dl class="method">
<dt id="png.Reader.asRGB8">
<tt class="descname">asRGB8</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.asRGB8" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the image data as an RGB pixels with 8-bits per
sample.  This is like the <a title="png.Reader.asRGB" class="reference internal" href="#png.Reader.asRGB"><tt class="xref docutils literal"><span class="pre">asRGB()</span></tt></a> method except that
this method additionally rescales the values so that they
are all between 0 and 255 (8-bit).  In the case where the
source image has a bit depth &lt; 8 the transformation preserves
all the information; where the source image has bit depth
&gt; 8, then rescaling to 8-bit values loses precision.  No
dithering is performed.  Like <a title="png.Reader.asRGB" class="reference internal" href="#png.Reader.asRGB"><tt class="xref docutils literal"><span class="pre">asRGB()</span></tt></a>, an alpha channel
in the source image will raise an exception.</p>
<p>This function returns a 4-tuple:
(<em>width</em>, <em>height</em>, <em>pixels</em>, <em>metadata</em>).
<em>width</em>, <em>height</em>, <em>metadata</em> are as per the <a title="png.Reader.read" class="reference internal" href="#png.Reader.read"><tt class="xref docutils literal"><span class="pre">read()</span></tt></a> method.</p>
<p><em>pixels</em> is the pixel data in boxed row flat pixel format.</p>
</dd></dl>

<dl class="method">
<dt id="png.Reader.asRGBA">
<tt class="descname">asRGBA</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.asRGBA" title="Permalink to this definition">¶</a></dt>
<dd>Return image as RGBA pixels.  Greyscales are expanded into
RGB triplets; an alpha channel is synthesized if necessary.
The return values are as for the <a title="png.Reader.read" class="reference internal" href="#png.Reader.read"><tt class="xref docutils literal"><span class="pre">read()</span></tt></a> method
except that the <em>metadata</em> reflect the returned pixels, not the
source image.  In particular, for this method
<tt class="docutils literal"><span class="pre">metadata['greyscale']</span></tt> will be <tt class="xref docutils literal"><span class="pre">False</span></tt>, and
<tt class="docutils literal"><span class="pre">metadata['alpha']</span></tt> will be <tt class="xref docutils literal"><span class="pre">True</span></tt>.</dd></dl>

<dl class="method">
<dt id="png.Reader.asRGBA8">
<tt class="descname">asRGBA8</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.asRGBA8" title="Permalink to this definition">¶</a></dt>
<dd>Return the image data as RGBA pixels with 8-bits per
sample.  This method is similar to <a title="png.Reader.asRGB8" class="reference internal" href="#png.Reader.asRGB8"><tt class="xref docutils literal"><span class="pre">asRGB8()</span></tt></a> and
<a title="png.Reader.asRGBA" class="reference internal" href="#png.Reader.asRGBA"><tt class="xref docutils literal"><span class="pre">asRGBA()</span></tt></a>:  The result pixels have an alpha channel, _and_
values are rescale to the range 0 to 255.  The alpha channel is
synthesized if necessary.</dd></dl>

<dl class="method">
<dt id="png.Reader.chunk">
<tt class="descname">chunk</tt><big>(</big><em>seek=None</em><big>)</big><a class="headerlink" href="#png.Reader.chunk" title="Permalink to this definition">¶</a></dt>
<dd>Read the next PNG chunk from the input file; returns type (as a 4
character string) and data.  If the optional <cite>seek</cite> argument is
specified then it will keep reading chunks until it either runs
out of file or finds the type specified by the argument.  Note
that in general the order of chunks in PNGs is unspecified, so
using <cite>seek</cite> can cause you to miss chunks.</dd></dl>

<dl class="method">
<dt id="png.Reader.chunklentype">
<tt class="descname">chunklentype</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.chunklentype" title="Permalink to this definition">¶</a></dt>
<dd>Reads just enough of the input to determine the next
chunk&#8217;s length and type, returned as a (<em>length</em>, <em>type</em>) pair
where <em>type</em> is a string.  If there are no more chunks, <tt class="xref docutils literal"><span class="pre">None</span></tt>
is returned.</dd></dl>

<dl class="method">
<dt id="png.Reader.chunks">
<tt class="descname">chunks</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.chunks" title="Permalink to this definition">¶</a></dt>
<dd>Return an iterator that will yield each chunk as a
(<em>chunktype</em>, <em>content</em>) pair.</dd></dl>

<dl class="method">
<dt id="png.Reader.deinterlace">
<tt class="descname">deinterlace</tt><big>(</big><em>raw</em><big>)</big><a class="headerlink" href="#png.Reader.deinterlace" title="Permalink to this definition">¶</a></dt>
<dd>Read raw pixel data, undo filters, deinterlace, and flatten.
Return in flat row flat pixel format.</dd></dl>

<dl class="method">
<dt id="png.Reader.iterboxed">
<tt class="descname">iterboxed</tt><big>(</big><em>rows</em><big>)</big><a class="headerlink" href="#png.Reader.iterboxed" title="Permalink to this definition">¶</a></dt>
<dd>Iterator that yields each scanline in boxed row flat pixel
format.  <cite>rows</cite> should be an iterator that yields the bytes of
each row in turn.</dd></dl>

<dl class="method">
<dt id="png.Reader.iterstraight">
<tt class="descname">iterstraight</tt><big>(</big><em>raw</em><big>)</big><a class="headerlink" href="#png.Reader.iterstraight" title="Permalink to this definition">¶</a></dt>
<dd>Iterator that undoes the effect of filtering, and yields each
row in serialised format (as a sequence of bytes).  Assumes input
is straightlaced.  <cite>raw</cite> should be an iterable that yields the
raw bytes in chunks of arbitrary size.</dd></dl>

<dl class="method">
<dt id="png.Reader.palette">
<tt class="descname">palette</tt><big>(</big><em>alpha='natural'</em><big>)</big><a class="headerlink" href="#png.Reader.palette" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a palette that is a sequence of 3-tuples or 4-tuples,
synthesizing it from the <tt class="docutils literal"><span class="pre">PLTE</span></tt> and <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunks.  These
chunks should have already been processed (for example, by
calling the <a title="png.Reader.preamble" class="reference internal" href="#png.Reader.preamble"><tt class="xref docutils literal"><span class="pre">preamble()</span></tt></a> method).  All the tuples are the
same size, 3-tuples if there is no <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk, 4-tuples when
there is a <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk.  Assumes that the image is colour type
3 and therefore a <tt class="docutils literal"><span class="pre">PLTE</span></tt> chunk is required.</p>
<p>If the <cite>alpha</cite> argument is <tt class="docutils literal"><span class="pre">'force'</span></tt> then an alpha channel is
always added, forcing the result to be a sequence of 4-tuples.</p>
</dd></dl>

<dl class="method">
<dt id="png.Reader.preamble">
<tt class="descname">preamble</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.preamble" title="Permalink to this definition">¶</a></dt>
<dd>Extract the image metadata by reading the initial part of the PNG
file up to the start of the <tt class="docutils literal"><span class="pre">IDAT</span></tt> chunk.  All the chunks that
precede the <tt class="docutils literal"><span class="pre">IDAT</span></tt> chunk are read and either processed for
metadata or discarded.</dd></dl>

<dl class="method">
<dt id="png.Reader.process_chunk">
<tt class="descname">process_chunk</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.process_chunk" title="Permalink to this definition">¶</a></dt>
<dd>Process the next chunk and its data.  This only processes the
following chunk types, all others are ignored: <tt class="docutils literal"><span class="pre">IHDR</span></tt>,
<tt class="docutils literal"><span class="pre">PLTE</span></tt>, <tt class="docutils literal"><span class="pre">bKGD</span></tt>, <tt class="docutils literal"><span class="pre">tRNS</span></tt>, <tt class="docutils literal"><span class="pre">gAMA</span></tt>, <tt class="docutils literal"><span class="pre">sBIT</span></tt>.</dd></dl>

<dl class="method">
<dt id="png.Reader.read">
<tt class="descname">read</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Read the PNG file and decode it.  Returns (<cite>width</cite>, <cite>height</cite>,
<cite>pixels</cite>, <cite>metadata</cite>).</p>
<p>May use excessive memory.</p>
<p><cite>pixels</cite> are returned in boxed row flat pixel format.</p>
</dd></dl>

<dl class="method">
<dt id="png.Reader.read_flat">
<tt class="descname">read_flat</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.read_flat" title="Permalink to this definition">¶</a></dt>
<dd><p>Read a PNG file and decode it into flat row flat pixel format.
Returns (<em>width</em>, <em>height</em>, <em>pixels</em>, <em>metadata</em>).</p>
<p>May use excessive memory.</p>
<p><cite>pixels</cite> are returned in flat row flat pixel format.</p>
<p>See also the <a title="png.Reader.read" class="reference internal" href="#png.Reader.read"><tt class="xref docutils literal"><span class="pre">read()</span></tt></a> method which returns pixels in the
more stream-friendly boxed row flat pixel format.</p>
</dd></dl>

<dl class="method">
<dt id="png.Reader.serialtoflat">
<tt class="descname">serialtoflat</tt><big>(</big><em>bytes</em>, <em>width=None</em><big>)</big><a class="headerlink" href="#png.Reader.serialtoflat" title="Permalink to this definition">¶</a></dt>
<dd>Convert serial format (byte stream) pixel data to flat row
flat pixel.</dd></dl>

<dl class="method">
<dt id="png.Reader.undo_filter">
<tt class="descname">undo_filter</tt><big>(</big><em>filter_type</em>, <em>scanline</em>, <em>previous</em><big>)</big><a class="headerlink" href="#png.Reader.undo_filter" title="Permalink to this definition">¶</a></dt>
<dd><p>Undo the filter for a scanline.  <cite>scanline</cite> is a sequence of
bytes that does not include the initial filter type byte.
<cite>previous</cite> is decoded previous scanline (for straightlaced
images this is the previous pixel row, but for interlaced
images, it is the previous scanline in the reduced image, which
in general is not the previous pixel row in the final image).
When there is no previous scanline (the first row of a
straightlaced image, or the first row in one of the passes in an
interlaced image), then this argument should be <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
<p>The scanline will have the effects of filtering removed, and the
result will be returned as a fresh sequence of bytes.</p>
</dd></dl>

<dl class="method">
<dt id="png.Reader.validate_signature">
<tt class="descname">validate_signature</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Reader.validate_signature" title="Permalink to this definition">¶</a></dt>
<dd>If signature (header) has not been read then read and
validate it; otherwise do nothing.</dd></dl>

</dd></dl>

<dl class="class">
<dt id="png.Writer">
<em class="property">
class </em><tt class="descclassname">png.</tt><tt class="descname">Writer</tt><big>(</big><em>width=None</em>, <em>height=None</em>, <em>size=None</em>, <em>greyscale=False</em>, <em>alpha=False</em>, <em>bitdepth=8</em>, <em>palette=None</em>, <em>transparent=None</em>, <em>background=None</em>, <em>gamma=None</em>, <em>compression=None</em>, <em>interlace=False</em>, <em>bytes_per_sample=None</em>, <em>planes=None</em>, <em>colormap=None</em>, <em>maxval=None</em>, <em>chunk_limit=1048576</em><big>)</big><a class="headerlink" href="#png.Writer" title="Permalink to this definition">¶</a></dt>
<dd><p>PNG encoder in pure Python.</p>
<p>Create a PNG encoder object.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt>width, height</dt>
<dd>Image size in pixels, as two separate arguments.</dd>
<dt>size</dt>
<dd>Image size (w,h) in pixels, as single argument.</dd>
<dt>greyscale</dt>
<dd>Input data is greyscale, not RGB.</dd>
<dt>alpha</dt>
<dd>Input data has alpha channel (RGBA or LA).</dd>
<dt>bitdepth</dt>
<dd>Bit depth: from 1 to 16.</dd>
<dt>palette</dt>
<dd>Create a palette for a colour mapped image (colour type 3).</dd>
<dt>transparent</dt>
<dd>Specify a transparent colour (create a <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk).</dd>
<dt>background</dt>
<dd>Specify a default background colour (create a <tt class="docutils literal"><span class="pre">bKGD</span></tt> chunk).</dd>
<dt>gamma</dt>
<dd>Specify a gamma value (create a <tt class="docutils literal"><span class="pre">gAMA</span></tt> chunk).</dd>
<dt>compression</dt>
<dd>zlib compression level (1-9).</dd>
<dt>interlace</dt>
<dd>Create an interlaced image.</dd>
<dt>chunk_limit</dt>
<dd>Write multiple <tt class="docutils literal"><span class="pre">IDAT</span></tt> chunks to save memory.</dd>
</dl>
<p>The image size (in pixels) can be specified either by using the
<cite>width</cite> and <cite>height</cite> arguments, or with the single <cite>size</cite>
argument.  If <cite>size</cite> is used it should be a pair (<em>width</em>,
<em>height</em>).</p>
<p><cite>greyscale</cite> and <cite>alpha</cite> are booleans that specify whether
an image is greyscale (or colour), and whether it has an
alpha channel (or not).</p>
<p><cite>bitdepth</cite> specifies the bit depth of the source pixel values.
Each source pixel values must be an integer between 0 and
<tt class="docutils literal"><span class="pre">2**bitdepth-1</span></tt>.  For example, 8-bit images have values
between 0 and 255.  PNG only stores images with bit depths of
1,2,4,8, or 16.  When <cite>bitdepth</cite> is not one of these values,
the next highest valid bit depth is selected, and an <tt class="docutils literal"><span class="pre">sBIT</span></tt>
(significant bits) chunk is generated that specifies the original
precision of the source image.  In this case the supplied pixel
values will be rescaled to fit the range of the selected bit depth.</p>
<p>The details of which bit depth / colour model combinations the
PNG file format supports directly, are allowed are somewhat arcane
(refer to the PNG specification for full details).  Briefly:
&#8220;small&#8221; bit depths (1,2,4) are only allowed with greyscale and
colour mapped images; colour mapped images cannot have bit depth
16.</p>
<p>For colour mapped images (in other words, when the <cite>palette</cite>
argument is specified) the <cite>bitdepth</cite> argument must match one of
the valid PNG bit depths: 1, 2, 4, or 8.  (It is valid to have a
PNG image with a palette and an <tt class="docutils literal"><span class="pre">sBIT</span></tt> chunk, but the meaning
is slightly different; it would be awkward to press the
<cite>bitdepth</cite> argument into service for this.)</p>
<p>The <cite>palette</cite> option, when specified, causes a colour mapped image
to be created: the PNG colour type is set to 3; greyscale
must not be set; alpha must not be set; transparent must
not be set; the bit depth must be 1,2,4, or 8.  When a colour
mapped image is created, the pixel values are palette indexes
and the <cite>bitdepth</cite> argument specifies the size of these indexes
(not the size of the colour values in the palette).</p>
<p>The palette argument value should be a sequence of 3- or
4-tuples.  3-tuples specify RGB palette entries; 4-tuples
specify RGBA palette entries.  If both 4-tuples and 3-tuples
appear in the sequence then all the 4-tuples must come
before all the 3-tuples.  A <tt class="docutils literal"><span class="pre">PLTE</span></tt> chunk is created; if there
are 4-tuples then a <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk is created as well.  The
<tt class="docutils literal"><span class="pre">PLTE</span></tt> chunk will contain all the RGB triples in the same
sequence; the <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk will contain the alpha channel for
all the 4-tuples, in the same sequence.  Palette entries
are always 8-bit.</p>
<p>If specified, the <cite>transparent</cite> and <cite>background</cite> parameters must
be a tuple with three integer values for red, green, blue, or
a simple integer (or singleton tuple) for a greyscale image.</p>
<p>If specified, the <cite>gamma</cite> parameter must be a positive number
(generally, a float).  A <tt class="docutils literal"><span class="pre">gAMA</span></tt> chunk will be created.  Note that
this will not change the values of the pixels as they appear in
the PNG file, they are assumed to have already been converted
appropriately for the gamma specified.</p>
<p>The <cite>compression</cite> argument specifies the compression level
to be used by the <tt class="docutils literal"><span class="pre">zlib</span></tt> module.  Higher values are likely
to compress better, but will be slower to compress.  The
default for this argument is <tt class="xref docutils literal"><span class="pre">None</span></tt>; this does not mean
no compression, rather it means that the default from the
<tt class="docutils literal"><span class="pre">zlib</span></tt> module is used (which is generally acceptable).</p>
<p>If <cite>interlace</cite> is true then an interlaced image is created
(using PNG&#8217;s so far only interace method, <em>Adam7</em>).  This does not
affect how the pixels should be presented to the encoder, rather
it changes how they are arranged into the PNG file.  On slow
connexions interlaced images can be partially decoded by the
browser to give a rough view of the image that is successively
refined as more image data appears.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Enabling the <cite>interlace</cite> option requires the entire image
to be processed in working memory.</p>
</div>
<p><cite>chunk_limit</cite> is used to limit the amount of memory used whilst
compressing the image.  In order to avoid using large amounts of
memory, multiple <tt class="docutils literal"><span class="pre">IDAT</span></tt> chunks may be created.</p>
<dl class="method">
<dt id="png.Writer.array_scanlines">
<tt class="descname">array_scanlines</tt><big>(</big><em>pixels</em><big>)</big><a class="headerlink" href="#png.Writer.array_scanlines" title="Permalink to this definition">¶</a></dt>
<dd>Generates boxed rows (flat pixels) from flat rows (flat pixels)
in an array.</dd></dl>

<dl class="method">
<dt id="png.Writer.array_scanlines_interlace">
<tt class="descname">array_scanlines_interlace</tt><big>(</big><em>pixels</em><big>)</big><a class="headerlink" href="#png.Writer.array_scanlines_interlace" title="Permalink to this definition">¶</a></dt>
<dd>Generator for interlaced scanlines from an array.  <cite>pixels</cite> is
the full source image in flat row flat pixel format.  The
generator yields each scanline of the reduced passes in turn, in
boxed row flat pixel format.</dd></dl>

<dl class="method">
<dt id="png.Writer.convert_pnm">
<tt class="descname">convert_pnm</tt><big>(</big><em>infile</em>, <em>outfile</em><big>)</big><a class="headerlink" href="#png.Writer.convert_pnm" title="Permalink to this definition">¶</a></dt>
<dd>Convert a PNM file containing raw pixel data into a PNG file
with the parameters set in the writer object.  Works for
(binary) PGM, PPM, and PAM formats.</dd></dl>

<dl class="method">
<dt id="png.Writer.convert_ppm_and_pgm">
<tt class="descname">convert_ppm_and_pgm</tt><big>(</big><em>ppmfile</em>, <em>pgmfile</em>, <em>outfile</em><big>)</big><a class="headerlink" href="#png.Writer.convert_ppm_and_pgm" title="Permalink to this definition">¶</a></dt>
<dd>Convert a PPM and PGM file containing raw pixel data into a
PNG outfile with the parameters set in the writer object.</dd></dl>

<dl class="method">
<dt id="png.Writer.file_scanlines">
<tt class="descname">file_scanlines</tt><big>(</big><em>infile</em><big>)</big><a class="headerlink" href="#png.Writer.file_scanlines" title="Permalink to this definition">¶</a></dt>
<dd>Generates boxed rows in flat pixel format, from the input file
<cite>infile</cite>.  It assumes that the input file is in a &#8220;Netpbm-like&#8221;
binary format, and is positioned at the beginning of the first
pixel.  The number of pixels to read is taken from the image
dimensions (<cite>width</cite>, <cite>height</cite>, <cite>planes</cite>) and the number of bytes
per value is implied by the image <cite>bitdepth</cite>.</dd></dl>

<dl class="method">
<dt id="png.Writer.make_palette">
<tt class="descname">make_palette</tt><big>(</big><big>)</big><a class="headerlink" href="#png.Writer.make_palette" title="Permalink to this definition">¶</a></dt>
<dd>Create the byte sequences for a <tt class="docutils literal"><span class="pre">PLTE</span></tt> and if necessary a
<tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk.  Returned as a pair (<em>p</em>, <em>t</em>).  <em>t</em> will be
<tt class="xref docutils literal"><span class="pre">None</span></tt> if no <tt class="docutils literal"><span class="pre">tRNS</span></tt> chunk is necessary.</dd></dl>

<dl class="method">
<dt id="png.Writer.write">
<tt class="descname">write</tt><big>(</big><em>outfile</em>, <em>rows</em><big>)</big><a class="headerlink" href="#png.Writer.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Write a PNG image to the output file.  <cite>rows</cite> should be
an iterable that yields each row in boxed row flat pixel format.
The rows should be the rows of the original image, so there
should be <tt class="docutils literal"><span class="pre">self.height</span></tt> rows of <tt class="docutils literal"><span class="pre">self.width</span> <span class="pre">*</span> <span class="pre">self.planes</span></tt> values.
If <cite>interlace</cite> is specified (when creating the instance), then
an interlaced PNG file will be written.  Supply the rows in the
normal image order; the interlacing is carried out internally.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Interlacing will require the entire image to be in working memory.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="png.Writer.write_array">
<tt class="descname">write_array</tt><big>(</big><em>outfile</em>, <em>pixels</em><big>)</big><a class="headerlink" href="#png.Writer.write_array" title="Permalink to this definition">¶</a></dt>
<dd>Write an array in flat row flat pixel format as a PNG file on
the output file.  See also <a title="png.Writer.write" class="reference internal" href="#png.Writer.write"><tt class="xref docutils literal"><span class="pre">write()</span></tt></a> method.</dd></dl>

<dl class="method">
<dt id="png.Writer.write_packed">
<tt class="descname">write_packed</tt><big>(</big><em>outfile</em>, <em>rows</em><big>)</big><a class="headerlink" href="#png.Writer.write_packed" title="Permalink to this definition">¶</a></dt>
<dd><p>Write PNG file to <cite>outfile</cite>.  The pixel data comes from <cite>rows</cite>
which should be in boxed row packed format.  Each row should be
a sequence of packed bytes.</p>
<p>Technically, this method does work for interlaced images but it
is best avoided.  For interlaced images, the rows should be
presented in the order that they appear in the file.</p>
<p>This method should not be used when the source image bit depth
is not one naturally supported by PNG; the bit depth should be
1, 2, 4, 8, or 16.</p>
</dd></dl>

<dl class="method">
<dt id="png.Writer.write_passes">
<tt class="descname">write_passes</tt><big>(</big><em>outfile</em>, <em>rows</em>, <em>packed=False</em><big>)</big><a class="headerlink" href="#png.Writer.write_passes" title="Permalink to this definition">¶</a></dt>
<dd><p>Write a PNG image to the output file.</p>
<p>Most users are expected to find the <a title="png.Writer.write" class="reference internal" href="#png.Writer.write"><tt class="xref docutils literal"><span class="pre">write()</span></tt></a> or
<a title="png.Writer.write_array" class="reference internal" href="#png.Writer.write_array"><tt class="xref docutils literal"><span class="pre">write_array()</span></tt></a> method more convenient.</p>
<p>The rows should be given to this method in the order that
they appear in the output file.  For straightlaced images,
this is the usual top to bottom ordering, but for interlaced
images the rows should have already been interlaced before
passing them to this function.</p>
<p><cite>rows</cite> should be an iterable that yields each row.  When
<cite>packed</cite> is <tt class="xref docutils literal"><span class="pre">False</span></tt> the rows should be in boxed row flat pixel
format; when <cite>packed</cite> is <tt class="xref docutils literal"><span class="pre">True</span></tt> each row should be a packed
sequence of bytes.</p>
</dd></dl>

</dd></dl>

<dl class="function">
<dt id="png.write_chunks">
<tt class="descclassname">png.</tt><tt class="descname">write_chunks</tt><big>(</big><em>out</em>, <em>chunks</em><big>)</big><a class="headerlink" href="#png.write_chunks" title="Permalink to this definition">¶</a></dt>
<dd>Create a PNG file by writing out the chunks.</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="">The png Module</a><ul>
<li><a class="reference external" href="#a-note-on-spelling-and-terminology">A note on spelling and terminology</a></li>
<li><a class="reference external" href="#a-note-on-formats">A note on formats</a></li>
<li><a class="reference external" href="#and-now-my-famous-members">And now, my famous members</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="ex.html"
                                  title="previous chapter">PyPNG Code Examples</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="chunk.html"
                                  title="next chapter">PNG: Chunk by Chunk</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/png.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="chunk.html" title="PNG: Chunk by Chunk"
             >next</a> |</li>
        <li class="right" >
          <a href="ex.html" title="PyPNG Code Examples"
             >previous</a> |</li>
        <li><a href="index.html">PyPNG v0.0.11 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2009, David Jones.
      Last updated on 2010-01-05T10:31:12.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.1.
    </div>
  </body>
</html>